
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;

namespace Swaf.BizObj
{
	/// <summary>
	/// When a class is going to act as a decorator specifically for bizobj fields, it has the option
	/// to implement this interface so that it can act as a "stand-in" for the field value during
	/// put and get calls.  If a class does not implement IBizObjDecorator, it must at least 
	/// implement the IDecorator interface, but it cannot be a field "stand-in".  This interface
	/// is used within the implementations of bizobj in order to help process the value going
	/// to and from client calls and allows the decorator to modify or even completely change
	/// the value of the object for the field.
	/// </summary>
	/// <remarks>
	/// In order for a class implementing this interface to be used on fields as a decorator
	/// it must also be registered in the BizObjFieldDecorators class factory.
	/// </remarks>
	public interface IBizObjDecorator : IDecorator
	{
		/// <summary>
		/// When put is called for a bizobj field that has standIn decorators, rather
		/// then putting the field directly into the bizobj it is passed down the
		/// collection of standIn decorators first.  If there are zero stand in decorators for 
		/// the field it is pushed directly into the bizobj.  If it has 1 or more
		/// standins then the value is pushed through them first and then the resulting value
		/// is pushed into the field map.
		/// </summary>
		/// <param name="parent">The bizobj parent that the field belongs to.</param>
		/// <param name="field">The field the decorator and value is applied to.</param>
		/// <param name="val">The value to be processed.  This starts as the value passed
		/// into the bizobj.put, but as it is passed to standins that can manipulate the value
		/// it is the results of this method.  For 2 standins on a given field, the first standin
		/// called gets the raw value from the call to put while the second standin gets the value
		/// modified from the first.</param>
		/// <param name="extraInfo">The extra info from the call to put.  This could be a value that
		/// directs the standin decorator on how to process the value.</param>
		/// <param name="shouldBeFieldType">if the value coming out of the decorator should be the same
		/// type of the field's defined type, then this should be true, otherwise false.  Sometimes a decorator
		/// will change the natural type of the field, if it does, it should set this value to false.</param>
		void put(IBizObj parent, IBizObjField field, ref object val, object extraInfo, ref bool shouldBeFieldType);

		/// <summary>
		/// When get is called for a bizobj field that has standin decorators, rather then
		/// just retrieving the value direclty from the bizobj and returning, it is retrieved
		/// from the standin decorators first.  If there are zero standins for the given field
		/// the value is returned raw.  If it has 1 or more standins, the value is retrieved first
		/// from the bizobj then passed to each standin for the value to be manipulated first.
		/// </summary>
		/// <param name="parent">The bizobj parent that the field belongs to.</param>
		/// <param name="field">The field the decorator and value is applied to.</param>
		/// <param name="val">The value to be returned to the caller of IBizObj.get.  The first
		/// standin gets the value directly from the bizobj and each successive standin gets the
		/// value from the previously called standin.</param>
		/// <param name="extraInfo"></param>
		/// <param name="shouldBeFieldType">if the value coming out of the decorator should be the same
		/// type of the field's defined type, then this should be true, otherwise false.  Sometimes a decorator
		/// will change the natural type of the field, if it does, it should set this value to false.</param>
		void get(IBizObj parent, IBizObjField field, ref object val, object[] extraInfo, ref bool shouldBeFieldType);

		/// <summary>
		/// When a bizobj is being created from XML or written as XML, decorators may change the default way
		/// in which the field will be written or read from XML.  During XML processing, an IBizObjField is
		/// asked if it uses the full the XML element or if it uses just the element's inner content.  The
		/// field will check its standin decorators to see if they modify the return value of this method.
		/// If one decorator returns false, the value for this method is false.  False, overrides true
		/// for this method.  As an example, if a field is a bizobj type, the IBizObjField would normally return
		/// true as the XML for the bizobj field includes the full XmlElement, not just its inner contents.  However
		/// a decorator may change the fundamental type of the field from a bizobj to a basic string (such
		/// as the encryption decorator does).  In that case, the full XmlElement may no longer needed because the
		/// decorator has all the information for the bizobj in the contents of the element.
		/// </summary>
		/// <returns>true if processing XML uses the full XML element (outer XML)</returns>
		bool doesUseFullXmlElement();
	}
}
